+2003-10-23 Federico Mena Quintero <federico@ximian.com>
+
+ * gtk/tmpl/gtkfilechooser.sgml: Added the text for the initial
+ section, and descriptions for the signals and enumerations.
+
+ * gtk/tmpl/gtkfilechooserdialog.sgml: Added the text for the
+ initial section, and a short example.
+
+ * gtk/tmpl/gtkfilechooserwidget.sgml: Added the text for the
+ initial section.
+
Fri Oct 24 00:25:07 2003 Matthias Clasen <maclas@gmx.de>
* gtk/tmpl/gtkfilefilter.sgml:
<SECTION>
<FILE>gtkfilechooser</FILE>
<TITLE>GtkFileChooser</TITLE>
-GtkFileChooser
GtkFileChooserAction
GTK_FILE_CHOOSER_ERROR
GtkFileChooserError
GTK_IS_FILE_CHOOSER
GTK_TYPE_FILE_CHOOSER
<SUBSECTION Private>
+GtkFileChooser
gtk_file_chooser_get_type
</SECTION>
GtkFileChooser
<!-- ##### SECTION Short_Description ##### -->
-an interface that represents a graphical file selector
+File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ #GtkFileChooser is an interface that can be implemented by file
+ selection widgets. In GTK+, the main objects that implement
+ this interface are #GtkFileChooserWidget and
+ #GtkFileChooserDialog. You do not need to write an object that
+ implements the #GtkFileChooser interface unless you are trying
+ to adapt an existing file selector to expose a standard
+ programming interface.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkFileChooser ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
-
-<!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
-<para>
-
-</para>
-
-@filechooser: the object which received the signal.
+ <para>
+ #GtkFileChooserDialog, #GtkFileChooserWidget
+ </para>
<!-- ##### ENUM GtkFileChooserAction ##### -->
-<para>
+ <para>
+ Describes whether a #GtkFileChooser is being used to open
+ existing files or to save to a possibly new file.
+ </para>
-</para>
-
-@GTK_FILE_CHOOSER_ACTION_OPEN:
-@GTK_FILE_CHOOSER_ACTION_SAVE:
+@GTK_FILE_CHOOSER_ACTION_OPEN: Indicates Open mode. The file chooser
+ will only let the user pick an existing file.
+@GTK_FILE_CHOOSER_ACTION_SAVE: Indicates Save mode. The file chooser
+ will let the user pick an existing file, or type in a new
+ filename.
<!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
-<para>
-
-</para>
+ Used to get the #GError quark for #GtkFileChooser errors.
+ </para>
<!-- ##### ENUM GtkFileChooserError ##### -->
-<para>
+ <para>
+ These identify the various errors that can occur while calling
+ #GtkFileChooser functions.
+ </para>
-</para>
-
-@GTK_FILE_CHOOSER_ERROR_NONEXISTENT:
-@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME:
+@GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
+@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
<!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
<para>
@Returns:
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
+End:
+-->
+
+
GtkFileChooserDialog
<!-- ##### SECTION Short_Description ##### -->
-implements GtkFileChooser as a dialog
-
+A file chooser dialog, suitable for "File/Open" or "File/Save" commands.
<!-- ##### SECTION Long_Description ##### -->
-<para>
+ <para>
+ #GtkFileChooserDialog is a dialog box suitable for use with
+ "File/Open" or "File/Save as" commands. This widget works by
+ putting a #GtkFileChooserWidget inside a #GtkDialog. It exposes
+ the #GtkFileChooserIface interface, so you can use all of the
+ #GtkFileChooser functions on the file chooser dialog as well as
+ those for #GtkDialog.
+ </para>
-</para>
+ <para>
+ Note that #GtkFileChooserDialog does not have any methods of its
+ own. Instead, you should use the functions that work on a
+ #GtkFileChooser.
+ </para>
-<!-- ##### SECTION See_Also ##### -->
-<para>
+ <example>
+ <title>Typical usage</title>
-</para>
+ <para>
+ In the simplest of cases, you can use #GtkFileChooserDialog
+ as in the following code:
+ </para>
+
+ <programlisting>
+GtkWidget *dialog;
+
+dialog = gtk_file_chooser_dialog_new ("Open File",
+ parent_window,
+ GTK_FILE_CHOOSER_ACTION_OPEN,
+ GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
+ GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
+ NULL);
+
+if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+ {
+ char *filename;
+
+ filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
+ open_file (filename);
+ g_free (filename);
+ }
+
+gtk_widget_destroy (dialog);
+ </programlisting>
+ </example>
+
+<!-- ##### SECTION See_Also ##### -->
+ <para>
+ #GtkFileChooser, #GtkDialog
+ </para>
<!-- ##### FUNCTION gtk_file_chooser_dialog_new ##### -->
<para>
@Returns:
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
+End:
+-->
+
+
GtkFileChooserWidget
<!-- ##### SECTION Short_Description ##### -->
-implements GtkFileChooser as an embeddable widget
+File chooser widget that can be embedded in other widgets.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+ <para>
+ #GtkFileChooserWidget is a widget suitable for selecting files.
+ It is the main building block of a #GtkFileChooserDialog. Most
+ applications will only need to use the latter; you can use
+ #GtkFileChooserWidget as part of a larger window if you have
+ special needs.
+ </para>
+
+ <para>
+ Note that #GtkFileChooserWidget does not have any methods of its
+ own. Instead, you should use the functions that work on a
+ #GtkFileChooser.
+ </para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ #GtkFileChooser, #GtkFileChooserDialog
+ </para>
<!-- ##### FUNCTION gtk_file_chooser_widget_new ##### -->
<para>
@Returns:
+
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
+End:
+-->
+
+
projects / gtk4.git / commitdiff